---
title: Theme
description: Learn how to customize your application's appearance using HeroUI's TailwindCSS plugin.
---

# Theme

Theming allows you to maintain a consistent look and feel across your application. HeroUI provides theme customization through a TailwindCSS plugin based on [tw-colors](https://github.com/L-Blondy/tw-colors), enabling you to easily customize colors, layouts and other UI elements.

<CarbonAd/>

## What is a Theme?

A theme is a predefined set of colors and layout attributes that ensure visual consistency across your application. It simplifies managing and updating your app's appearance.

## Setup

The first step to using HeroUI's theming capability is adding the `heroui` plugin to your
`tailwind.config.js` file. Below is an example of how to do this:

<Blockquote color="primary">
**Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`
</Blockquote>

```js {9,14-15}
// tailwind.config.js
const {heroui} = require("@heroui/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
    // make sure it's pointing to the ROOT node_module
    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [heroui()],
};
```

### Usage

After adding the plugin to your `tailwind.config.js` file, you can utilize any of the default
themes (light/dark) or a custom one. Here's how you can apply these themes in your `main.jsx` or `main.tsx`:

Go to the src directory and inside `main.jsx` or `main.tsx`, apply the following class names to the root element:

- `light` for the light theme.
- `dark` for the dark theme.
- `text-foreground` to set the text color.
- `bg-background` to set the background color.

```jsx {11}
// main.tsx or main.jsx
import React from "react";
import ReactDOM from "react-dom/client";
import {HeroUIProvider} from "@heroui/react";
import App from "./App";
import "./index.css";

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <HeroUIProvider>
      <main className="dark text-foreground bg-background">
        <App />
      </main>
    </HeroUIProvider>
  </React.StrictMode>,
);
```

> **Note**: See the [Colors](/docs/customization/colors) section to learn more about the color classes.

### Default Plugin Options

The `heroui` plugin provides a default structure. It is outlined as follows:

```js
module.exports = {
  plugins: [
    heroui({
      prefix: "heroui", // prefix for themes variables
      addCommonColors: false, // override common colors (e.g. "blue", "green", "pink").
      defaultTheme: "light", // default theme from the themes object
      defaultExtendTheme: "light", // default theme to extend on custom themes
      layout: {}, // common layout tokens (applied to all themes)
      themes: {
        light: {
          layout: {}, // light theme layout tokens
          colors: {}, // light theme colors
        },
        dark: {
          layout: {}, // dark theme layout tokens
          colors: {}, // dark theme colors
        },
        // ... custom themes
      },
    }),
  ],
};
```

### Themes Options

These are the options that you can use to apply custom configurations to your themes.

```js {6-7,10-11}
module.exports = {
  plugins: [
    heroui({
      themes: {
        light: {
          layout: {},
          colors: {}
        },
        dark: {
          layout: {},
          colors: {}
        },
        ... // custom themes
      }
    })
  ]
}
```

### Nested themes

HeroUI supports nested themes, allowing you to apply different themes to different sections
of your application:

```html
<html class="dark">
  ...
  <div class="light">...</div>
  <div class="purple-dark">...</div>
</html>
```

### Theme based variants

HeroUI enables you to apply TailwindCSS styles based on the currently active theme. Below are
examples of how to do this:

```html
<!-- In dark theme, background will be dark and text will be light. 
  In light theme, background will be light and text will be dark -->

<div class="dark dark:bg-gray-800 dark:text-white bg-white text-black">
  ...
  <div>Text color changes based on theme</div>
</div>

<div class="light light:bg-gray-100 light:text-black bg-black text-white">
  ...
  <div>Text color changes based on theme</div>
</div>
```

### API Reference

The following table provides an overview of the various attributes you can use when working
with themes in HeroUI:

| Attribute          | Type                          | Description                                                                                                     | Default  |
| ------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- |
| prefix             | `string`                      | The prefix for the css variables.                                                                               | `heroui` |
| addCommonColors    | `boolean`                     | If true, the common heroui colors (e.g. "blue", "green", "purple") will replace the TailwindCSS default colors. | `false`  |
| defaultTheme       | `light` \| `dark`             | The default theme to use.                                                                                       | `light`  |
| defaultExtendTheme | `light` \| `dark`             | The default theme to extend.                                                                                    | `light`  |
| layout             | [LayoutTheme](#layouttheme)   | The layout definitions.                                                                                         | -        |
| themes             | [ConfigThemes](#configthemes) | The theme definitions.                                                                                          | -        |

### Types

#### ConfigThemes

```ts
type ConfigTheme = {
  extend?: "light" | "dark"; // base theme to extend
  layout?: LayoutTheme; // see LayoutTheme
  colors?: ThemeColors; // see ThemeColors
};

type ConfigThemes = Record<string, ConfigTheme>;
```

#### LayoutTheme

```ts
type BaseThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
};

type FontThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
  tiny?: string;
};

interface LayoutTheme {
  /**
   * The default font size applied across the components.
   */
  fontSize?: FontThemeUnit;
  /**
   * The default line height applied across the components.
   */
  lineHeight?: FontThemeUnit;
  /**
   * The default radius applied across the components.
   * we recommend to use `rem` units.
   */
  radius?: BaseThemeUnit;
  /**
   * A number between 0 and 1 that is applied as opacity-[value] when
   * the component is disabled.
   */
  disabledOpacity?: string | number;
  /**
   * The default height applied to the divider component.
   * we recommend to use `px` units.
   */
  dividerWeight?: string;
  /**
   * The border width applied across the components.
   */
  borderWidth?: BaseThemeUnit;
  /**
   * The box shadow applied across the components.
   */
  boxShadow?: BaseThemeUnit;
}
```

#### ThemeColors

```ts
type ColorScale = {
  50: string;
  100: string;
  200: string;
  300: string;
  400: string;
  500: string;
  600: string;
  700: string;
  800: string;
  900: string;
  foreground: string; // contrast color
  DEFAULT: string;
};

type BaseColors = {
  background: ColorScale; // the page background color
  foreground: ColorScale; // the page text color
  divider: ColorScale; // used for divider and single line border
  overlay: ColorScale; // used for modal, popover, etc.
  focus: ColorScale; // used for focus state outline
  content1: ColorScale; // used for card, modal, popover, etc.
  content2: ColorScale;
  content3: ColorScale;
  content4: ColorScale;
};

// brand colors
type ThemeColors = BaseColors & {
  default: ColorScale;
  primary: ColorScale;
  secondary: ColorScale;
  success: ColorScale;
  warning: ColorScale;
  danger: ColorScale;
};
```
